Skip to main content

Management API

Tidecloak provides a Management API that allows you to programmatically manage realms, clients, users, roles, and other resources in Tidecloak. This API is RESTful and can be used to automate administrative tasks.

Below is a guide to using Tidecloak's Management API for common tasks such as managing realms, clients, users, and roles.

1. Set Up Tidecloak​

Before using the Management API, ensure you have:

  • A running Tidecloak server.
  • An admin account with sufficient privileges.
  • A client configured for administrative access (e.g., admin-cli).

2. Obtain an Admin Access Token​

To use the Management API, you need an access token with administrative privileges. Use the /token endpoint to authenticate as an admin user.

Request​

  • Method : POST
  • URL : http://<Tidecloak-server>/auth/realms/master/protocol/openid-connect/token
  • Headers :
  • Content-Type: application/x-www-form-urlencoded
  • Body (form-urlencoded):
    • grant_type: password
    • client_id: admin-cli (or your admin client)
    • username: Admin username (e.g., admin)
    • password: Admin password

Example​

curl -X POST \
  http://localhost:8080/auth/realms/master/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=admin" \
  -d "grant_type=password"

Response​

{
  "access_token": "<admin-access-token>",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "<refresh-token>",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "<session-state>",
  "scope": "profile email"
}

3. Tidecloak Management API Endpoints​

The base URL for the Management API is:

http://<Tidecloak-server>/auth/admin/realms/<realm>

Common Endpoints​

  • Realms : /realms
  • Clients : /clients
  • Users : /users
  • Roles : /roles
  • Groups : /groups

4. Manage Realms​

Create a Realm​

  • Method : POST

  • URL : http://<Tidecloak-server>/auth/admin/realms

  • Headers :

  • Content-Type: application/json

  • Authorization: Bearer <admin-access-token>

  • Body (JSON):

    {
      "realm": "my-new-realm",
      "enabled": true
    }

Example​

curl -X POST \
  http://localhost:8080/auth/admin/realms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-access-token>" \
  -d '{
    "realm": "my-new-realm",
    "enabled": true
  }'

Get All Realms​

  • Method : GET
  • URL : http://<Tidecloak-server>/auth/admin/realms

Example​

curl -X GET \
  http://localhost:8080/auth/admin/realms \
  -H "Authorization: Bearer <admin-access-token>"

5. Manage Clients​

Create a Client​

  • Method : POST

  • URL : http://<Tidecloak-server>/auth/admin/realms/<realm>/clients

  • Headers :

  • Content-Type: application/json

  • Authorization: Bearer <admin-access-token>

  • Body (JSON):

    {
      "clientId": "my-client",
      "enabled": true,
      "redirectUris": ["http://localhost:3000/*"],
      "publicClient": false
    }

Example​

curl -X POST \
  http://localhost:8080/auth/admin/realms/my-realm/clients \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-access-token>" \
  -d '{
    "clientId": "my-client",
    "enabled": true,
    "redirectUris": ["http://localhost:3000/*"],
    "publicClient": false
  }'

Get All Clients​

  • Method : GET
  • URL : http://<Tidecloak-server>/auth/admin/realms/<realm>/clients

Example​

curl -X GET \
  http://localhost:8080/auth/admin/realms/my-realm/clients \
  -H "Authorization: Bearer <admin-access-token>"

6. Manage Users​

Create a User​

  • Method : POST

  • URL : http://<Tidecloak-server>/auth/admin/realms/<realm>/users

  • Headers :

  • Content-Type: application/json

  • Authorization: Bearer <admin-access-token>

  • Body (JSON):

    {
      "username": "user1",
      "enabled": true,
      "email": "user1@example.com",
      "firstName": "User",
      "lastName": "One",
      "credentials": [
        {
          "type": "password",
          "value": "password",
          "temporary": false
        }
      ]
    }

Example​

curl -X POST \
  http://localhost:8080/auth/admin/realms/my-realm/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-access-token>" \
  -d '{
    "username": "user1",
    "enabled": true,
    "email": "user1@example.com",
    "firstName": "User",
    "lastName": "One",
    "credentials": [
      {
        "type": "password",
        "value": "password",
        "temporary": false
      }
    ]
  }'

Get All Users​

  • Method : GET
  • URL : http://<Tidecloak-server>/auth/admin/realms/<realm>/users

Example​

curl -X GET \
  http://localhost:8080/auth/admin/realms/my-realm/users \
  -H "Authorization: Bearer <admin-access-token>"

7. Manage Roles​

Create a Role​

  • Method : POST

  • URL : http://<Tidecloak-server>/auth/admin/realms/<realm>/roles

  • Headers :

  • Content-Type: application/json

  • Authorization: Bearer <admin-access-token>

  • Body (JSON):

    {
      "name": "my-role"
    }

Example​

curl -X POST \
  http://localhost:8080/auth/admin/realms/my-realm/roles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-access-token>" \
  -d '{
    "name": "my-role"
  }'

Get All Roles​

  • Method : GET
  • URL : http://<Tidecloak-server>/auth/admin/realms/<realm>/roles

Example​

curl -X GET \
  http://localhost:8080/auth/admin/realms/my-realm/roles \
  -H "Authorization: Bearer <admin-access-token>"

8. Error Handling​

Tidecloak Management API returns standard HTTP status codes and error messages. For example:

  • 400 Bad Request: Invalid request parameters.
  • 401 Unauthorized: Invalid or expired token.
  • 403 Forbidden: Insufficient permissions.

Error responses typically include a JSON body with details:

{
  "error": "invalid_request",
  "error_description": "Invalid request parameters"
}